<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
        <title>MuStafService.jar README</title>
    </head>
    <body>
        <h2>About MuStafService.jar</h2>
        <p>
            By using this code, you agree to abide by the terms of this <a href="./LICENSE_Creative_Commons.html">LICENSE.</a>
        </p>
        <p>
            For more information about Google Code from Mu Dynamics, please see the <a href="http://code.google.com/p/mu-labs/w/list">mu-labs Google 
                Code Wiki.</a>
        </p>
		<p>There are some unit tests under src/test.</p>
        <h3>MuStafService was developed using</h3>
        <ul>
            <li>
                <a href="http://java.sun.com/javase/downloads/index_jdk5.jsp">Java 1.5</a>
                aka JDK 5
            </li>
            <li>
                <a href="https://jax-ws.dev.java.net/2.1.3">jaxws-ri 2.3</a>
            </li>
            <li>
                <a href="http://www.eclipse.org/downloads/">eclipse Java IDE</a>
            </li>
        </ul>
        <p>
            The WSDL-derived objects were generated using <a href="http://java.sun.com/javase/6/docs/technotes/tools/share/wsimport.html">wsimport,</a>
            located inside $JAXWS_HOME/bin. I have included the generated source, and byte-compiled 
            MuStafService.jar files in this distribution for the sake of convenience.   
			If you make any changes to the code, obviously you will need to regenerate the .java and subsequently, 
			.class files, yourself.
        </p>
        <p>
            Eclipse was used for building and exporting to JAR.   Here is a <a href="STAFinEclipse.html">generic how-to</a>
            that was written for this.
        </p>
        <h2>Installation</h2>
        <ol>
            <li>
                Download and install Java 1.5/JDK 5 (see link above)
            </li>
            <li>
                Download and install jaxws-ri 2.3 (see link above)
            </li>
			<li>Modify STAF.cfg as outlined below
			</li>
            <li>
                Set up the Java and other environment variables as shown below
            </li>
            <li>
                Copy MuStafService.jar to $STAF_HOME/lib
            </li>
        </ol>
        <h3>To put in STAF.cfg under Mac OS X (modify to suit Win & Linux):</h3>
        <blockquote>
            <pre>SET DATADIR /Library/staf/data
SET VAR MULOGIN=login
SET VAR MUPASSWORD=password
SET VAR MUIPADDR=n.n.n.n
SERVICE Mu library JSTAF execute ....staf/lib/MuStafService.jar OPTION JVM=/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Commands/java
</pre>
        </blockquote>
        <p>
            For some reason STAF  failed to launch the JVM unless specified the location of the JVM explicitly; 
            you probably will not need to define JVM explicitly.
        </p>
        <p>
            Alternatively, if you want to debug you can do so by changing the last line to read:<pre>SERVICE Mu library JSTAF execute ....staf/lib/MuStafService.jar OPTION JVM=/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Commands/java \
OPTION "J2=-Xdebug -Xrunjdwp:transport=dt_socket,suspend=n,server=y,address=7777"</pre>
        </p>
        <p>
            If you want to compile this from the command line, just use the insructions 
            as given in the <a href="http://staf.sourceforge.net/current/stafsdg.html#Header_Debugging_Java_Service">STAF Service Developer's Guide</a>
        </p>
        <h3>Environment variables for Mac OS X (modify to suit Win & Linux):</h3>
        <blockquote>
            <pre>
export DYLD_LIBRARY_PATH=/Library/staf/lib:$DYLD_LIBRARY_PATH
export JAVA_HOME=/Library/Java/Home
export JAXWS_HOME=$JAVA_HOME/jaxws-ri
export STAF_HOME=/Library/staf
export CLASSPATH=$JAXWS_HOME/lib/jaxws-rt.jar:$JAXWS_HOME/lib/mimepull.jar:$JAXWS_HOME/lib/saaj-api.jar:$JAXWS_HOME/lib/saaj-impl.jar:$JAXWS_HOME/lib/stax-ex.jar:$JAXWS_HOME/lib/streambuffer.jar:$JAXWS_HOME/lib/resolver.jar:$JAXWS_HOME/lib/jaxb-impl.jar:$JAXWS_HOME/lib/sjsxp.jar:$JAXWS_HOME/lib/jaxb-rt.jar:$JAXWS_HOME/lib/jaxb-api.jar:$JAXWS_HOME/lib/jaxws-api.jar:$JAXWS_HOME/lib/jsr173_api.jar:$JAXWS_HOME/lib/jsr181-api.jar:$STAF_HOME/lib/JSTAF.jar
</pre>
        </blockquote>
        <h2>Troubleshooting</h2>
        <h3>The log file for MuStafService is in</h3>
        <code>
            $STAF_HOME/data/lang/java/jvm/mustafjvm/JVMLog.1 
        </code>
        If you forget to leave a blank line at the end of your MANIFEST.MF, you may see the following error:
        <blockquote>
            <code>
                $ STAFProc 
                <br>
                Error on Service definition, SERVICE Mu library JSTAF execute /Library/staf/lib/MuStafService.jar OPTION JVM=/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Commands/java
                38:Error constructing service, JSTAF, Result: Invalid manifest for STAF service: No Service-Class attribute
                Error reading config file
            </code>
        </blockquote>
        <h3>Known issues:</h3>
        On terminating STAFProc:
        <br/>
        20080618-18:28:18;0xa000d000;00000100;Error terminating service, MU, RC: 5, Result: Error terminating service, JSTAF, Result: HandleManager::updateTimestamp() failed to update handle 3
    </body>
</html>
